Any fool can write code that a computer can understand. Good programmers write code that humans can understand.
Martin Fowler, 2008
Often programming is seen as the stupid necessarily at the end of the interesting parts of application development. A job that can be done by some code monkey - since everybody can program...
In my daily job as application developer I found some examples that may result by those opinions (sorry for the COBOL source...):
EVALUATE TRUE
WHEN IN-DATE-TYPE-CODE = '2'
MOVE IN-DATE-TYPE-CODE TO OUT-DATE-TYPE-CODE
MOVE IN-START-DATE TO OUT-START-DATE
MOVE IN-END-DATE TO OUT-END-DATE
WHEN OTHER
MOVE '2' TO OUT-DATE-TYPE-CODE
MOVE IN-START-DATE TO OUT-START-DATE
MOVE IN-END-DATE TO OUT-END-DATE
END-EVALUATE
The sample above made me curious so I really tried to understand the intention of the creator. Was this tautology thought to be more readable? Was there another option in a previous version of the code (due to the version history: NO)? Did he know what he was doing?
Finally I gave up and committed a version that just fills the OUT-DATE-TYPE-CODE with '2' every time... nothing but the maintainability changed.
A slightly more complex example is shown below (note: LOW-VALUE means HEX 00 in COBOL and alphanumeric fields can be compared by their HEX VALUE ('A' > SPACE)):
IF FIELD-A = LOW-VALUE OR SPACE
MOVE LOW-VALUE TO OUT-FIELD
ELSE
MOVE FIELD-A TO OUT-FIELD
END-IF
IF OUT-FIELD = LOW-VALUE
IF FIELD-B = SPACE OR LOW-VALUE
MOVE LOW-VALUE TO OUT-FIELD
ELSE
MOVE FIELD-B TO OUT-FIELD
END-IF
END-IF
This code is quiet hard to read (even after I removed a lot of noise that was in the actual program...). As a first step the common initialization values (LOW-VALUE and SPACE) of FIELD-A are checked (so control characters as HEX 01 - 39 (EBCDIC) are seen as valid - which is a severe error in this context). If the value is invalid the target field gets initialized. Later in the code this initialization is checked again and afterwards another field may be moved into the target OUT-FIELD.
All this confusing code may be reduced to:
EVALUATE TRUE
WHEN FIELD-A > SPACE
MOVE FIELD-A TO OUT-FIELD
WHEN FIELD-B > SPACE
MOVE FIELD-B TO OUT-FIELD
WHEN OTHER
MOVE LOW-VALUE TO OUT-FIELD
END-EVALUATE
Again the code does the same as before (it is just more secure against errors due to control characters) BUT it can be read and understand way easier.
The two anecdotal examples above are just to illustrate the point that good source code is more than 'something that does it' it is also important to illustrate what the code should do- a future developer (or even future you) will thank you.